Release 10.1A: OpenEdge Development:
ADM and SmartObjects

SmartFilter instance properties

The main purpose of SmartFilter instance properties is to allow you to select fields from the SmartDataObject that serves as the SmartFilter’s Filter-Target and customize how application users specify filter data.

Figure 2–11 shows the SmartFilter instance properties dialog box.

Figure 2–11: SmartFilter Properties dialog box

Instance properties in this dialog box are grouped into the following panes:

Data pane
Field Properties pane
Style pane
String Operators pane
Operator View as pane
Size & Position pane

A final instance property, View, is not in any group.

You use these instance properties as described in the following sections.

Data pane

You use the instance properties in the Data pane to define the SmartDataObject that will serve as the SmartFilter’s Filter-Target and specify the SmartDataObject fields that are available to the SmartFilter:

Target, Browse — If your SmartFilter already is linked to a SmartDataObject that will serve as its Filter-Target, the Target field lists that SmartDataObject and is disabled; you cannot specify another value.

The Target field is enabled, however, if you open the instance properties dialog box without linking the SmartFilter to a Filter-Target. You might want to create a SmartFilter without a link, for example, because you placed it in a SmartContainer and intend to link it to a Filter-Target in another SmartContainer. The Browse button opens a window in which you can browse to and select a SmartDataObject.

Note: This SmartDataObject is only design-time SmartDataObject. You must ensure it is linked at run time.
Fields, Edit Field List — The Fields list box lists the filter fields that will appear in the SmartFilter, in the order in which they will be shown. The Edit Field List button opens a window in which you can select, deselect, and reorder these fields.

Field Properties pane

Because the fields that appear in the SmartFilter are generated dynamically, you cannot access most of their properties in the AppBuilder; however, the SmartFilter’s instance property provides access to a few field properties. Select a field in the Fields list box, and its property values appear in the Field Properties pane.

Changes entered into a control in the Field Properties pane take effect as soon as you select another field in the Fields list box. Pressing OK in the dialog box saves all field property value changes, including any that are not displayed:

Label, Filter Target — The Label fill-in field displays the label of the selected field. By default, the AppBuilder uses the label from the data source and disables this field. To enable the Label field so you can enter your own label, uncheck Filter Target.
Width, Default — The Width fill-in field displays the width of the selected field. By default, the AppBuilder uses the default field width and disables this field. (The default field width is data-type dependent and is specified in the Size & Position pane. See the "Size & Position pane" section.) To enable the Width field so you can enter your own value, uncheck Default.
Tooltip — Enter the text of the tooltip for this field. There is no default.
Help ID — Enter the context ID for the relevant help topic. There is no default.
View as range fields, Explicit operator— These check boxes override the default filter style (see the "Style pane" section for details) for the field selected in the Fields fill-in field:
The View as range fields check box gives the selected field the same visualization as the Range style gives to all fields.
The Explicit operator check box assigns the same operator to the selected field as the Explicit style gives to all fields.

You can check only one of these boxes. One or both might be disabled, depending on your choice of default filter style:

If the default filter style is Inline, neither check box is enabled.
If the style is Explicit or Implicit, only the View as range fields check box is enabled.
If the style is Range, only the Explicit operator check box is enabled.

Style pane

You use this set of radio buttons to specify the default filter style, which defines how the AppBuilder visualizes the fields in the SmartFilter and applies the application user’s filter criteria to the query:

Implicit — This generates a single list of fill-in fields in which the application user can specify filter data at run time. Each field is assigned the appropriate data type, thus restricting the filter data entered by the user to the correct data type. You specify in the associated combo box the implicit operator to be used with the filter data.

In some cases, other SmartFilter properties might override the default behavior of the Implicit style:

If you check the BEGINS property, the AppBuilder uses the BEGINS operator for character fields regardless of your choice of operator. (This is the default.)
If you check the CONTAINS property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word-indexed database fields, regardless of your choice of operator. In addition, these fields are visualized as editors rather than fill-in fields, with their height and word-wrap capabilities regulated by the Number of Lines in Editors property.

See the "String Operators pane" section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the "Size & Position pane" section.

The Implicit style supports wild cards, but only if you do not check the BEGINS property. There is one exception: a value that starts with a wild card always generates an expression with the Progress MATCHES keyword.

Explicit — This shows, after a filter field, a list of selectable operators from which the application user can select at run time. The operator is visualized as either a combo box or a radio set, depending on how you set the properties in the Operator View as pane. For details, see the "Operator View as pane" section.

Selecting the Explicit style disables the BEGINS property. (This is because BEGINS is in the operator list for character fields.) For details, see the "String Operators pane" section.

Range — This generates two lists of each filter field, allowing the application user to specify a range of inclusive values as filter data at run time. The left-hand set of fields support wild cards.

Selecting the Range style disables the BEGINS property. However, the CONTAINS string operator property might override the default behavior of the Range style. If you check this property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word-indexed database fields, instead of a range of values. In addition, these fields are visualized as editors rather than fill-in fields, with their height and word-wrap capabilities regulated by the Number of Lines in Editors property.

See the "String Operators pane" section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the "Size & Position pane" section.

Inline — This generates a single list of fields for which the application user can enter the filter data and an operator at run time. All fields are represented as character fields to allow typing the operator names. The default operator, which the AppBuilder uses if the user does not enter an operator, is EQUALS.

In some cases, other SmartFilter properties might override the default behavior of the Inline style:

If you check the BEGINS property, the AppBuilder uses the BEGINS operator as the default operator for character fields instead of EQUALS.
If you check the CONTAINS property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word-indexed database fields, regardless of the user’s choice of operator (or the default operator, if relevant). In addition, these fields are visualized as editors rather than fill-in fields, with their height and word-wrap capabilities regulated by the Number of Lines in Editors property.

See the "String Operators pane" section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the "Size & Position pane" section.

The Inline style supports wild cards, but only if you do not check the BEGINS property. There is one exception: a value that starts with a wild card always generates an expression with the Progress MATCHES keyword.

String Operators pane

You use these check boxes to specify certain overrides for the default filter styles, For details, see the "Style pane" section:

BEGINS — If checked, this specifies the following:
If the default filter style is Implicit, Progress uses the BEGINS operator for character fields instead of the implicit operator that you specify.
If the default filter style is Inline, Progress uses BEGINS as the default operator for character fields. (The default operator is used when application users do not specify an operator.)

The BEGINS property is disabled for the Explicit and Range filter styles.

CONTAINS — If this is checked, and the default filter style is Implicit, Range, or Inline, specifies that the AppBuilder uses CONTAINS as the operator for filter fields that are mapped to word-wrapped database fields, regardless of the operator specified for that style. In addition, these fields are visualized as editors rather than fill-in fields, with their height and word-wrap capabilities regulated by the Number of Lines in Editors property. For details, see the "Size & Position pane" section.

Operator View as pane

You use this set of radio buttons to specify how the AppBuilder visualizes the operator selection provided when you select Explicit as the default filter style. For details, see the "Style pane" section:

Combo-box — This visualizes the operator selection as a combo box.
Radio-set — This visualizes the operator selection as a radio set.

These radio buttons are disabled if the default filter style is Implicit or Inline. They are enabled if the default filter style is Range, in case you choose to override the style for a specific field to Explicit with the Explicit operator property. For details, see the "Field Properties pane" section.

Size & Position pane

You use the instance properties in the Size & Position pane to define various aspects of filter fields:

Width of Character Fields — This specifies the default width of character fields.
Width of Other Fields — This specifies the default width of noncharacter fields.
Column — this specifies the column position of all fields.
Note: This is the position of the actual field and not the label.
Number of Lines in Editors — When you check the CONTAINS property (see the "String Operators pane" section), the AppBuilder visualizes certain filter fields as editors rather than fill-in fields. This property specifies the number of lines to use for these editors. If you specify 1, the editor has the same height as fill-in fields and word wrapping is disabled. If you specify 2, the editor shows two lines, word wrapping is enabled, and a vertical scroll bar appears.

View property

If checked (the default), the View check box makes the SmartFilter visible.